# ROS 2 Humble安装指南

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

本文档说明在 Quectel Pi 开发板（Debian 13 trixie / ARM64）上从源码构建 ROS 2 Humble 的方法。ROS 2 Humble 官方发行版面向 Ubuntu 22.04，Debian 13 下无现成 apt 包，需在板端从源码构建。本文档所有步骤均在内核 6.1.118-rt36（PREEMPT_RT）、Python 3.13.5、3.9 GB 内存的开发板上实测通过。

## 简介

ROS 2（Robot Operating System 2）是面向机器人开发的分布式通信框架，Humble 为其长期支持（LTS）版本。在开发板上从源码构建 ROS 2 Humble 的特点：

- 可裁剪：只构建需要的功能包（RMW 使用 Cyclone DDS，跳过 Connext 等商业中间件）；

- 板端验证：直接基于开发板的 Debian 13 系统构建，产物与硬件环境匹配；

- 可复现：工作空间结构与构建参数可模板化，便于 CI 与多设备同步。

**磁盘空间提示：** 完整编译需 10 GB 以上空间。开发板根分区（/）实测 51 GB（可用约 44 GB）充足，工作空间直接部署在 `/root/ros2_humble`，无需额外分区。

## 准备工作

### 系统要求

| **项目** | **要求** |
| --- | --- |
| 操作系统 | Debian GNU/Linux 13 (trixie)，实测版本 13.6 |
| 架构 | ARM64（aarch64） |
| 内核 | 实测 6.1.118-rt36（PREEMPT_RT） |
| 磁盘 | 根分区 ≥ 10 GB（实测 51 GB）；源码约 654 MB，编译产物约 3 GB |
| 内存 | ≥ 3 GB（实测 3.9 GB，无 swap，编译需限制并行度，见编译问题 2） |
| 网络 | 可访问 GitHub（克隆源码）与 Debian 软件源（安装依赖） |
| 编译时间 | demo_nodes 依赖链约 40 分钟（8 核限并行 4） |

## 安装步骤

### 安装基础依赖包

```bash
sudo apt-get update
sudo apt-get install -y \
    python3-flake8-blind-except python3-flake8-class-newline python3-flake8-deprecated \
    python3-mypy python3-pip python3-pytest python3-pytest-cov python3-pytest-mock \
    python3-pytest-repeat python3-pytest-rerunfailures python3-pytest-runner \
    python3-pytest-timeout python3-rosdep2 python3-colcon-core \
    vcstool build-essential git cmake \
    python3-numpy python3-numpy-dev \
    libacl1-dev uncrustify

# 注意：Debian 的 python3-colcon-core 仅提供库，无 CLI 入口，需再安装 colcon（见编译问题 1）
sudo apt-get install -y colcon

```

### 创建工作空间

```bash
mkdir -p /root/ros2_humble/src
cd /root/ros2_humble

```

### 获取 ROS 2 Humble 源代码

```bash
cd /root/ros2_humble
mkdir -p src
wget https://raw.githubusercontent.com/ros2/ros2/humble/ros2.repos
vcs import src < ros2.repos

```

ros2.repos 包含约 100 个仓库（实测 104 个），源码约 654 MB。若 vcs 卡在某仓库（如 Fast-DDS 大仓库），可改用浅克隆脚本逐个拉取。

### 安装系统依赖项

```bash
sudo rosdep init
rosdep update
cd /root/ros2_humble
rosdep install --from-paths src --ignore-src --rosdistro humble -y -r \
  --skip-keys "fastcdr rti-connext-dds-6.0.1 urdfdom_headers python3-vcstool \
              ignition-math6 ignition-cmake2 ignition-common3 ignition-transport8"

```

**跳过的包说明：** fastcdr、rti-connext-dds（商业/可选）；urdfdom_headers、python3-vcstool（已装）；ignition-*（Debian 13 不可用，Gazebo 相关）。

**常见错误（可忽略）：** python3-sip-dev 失败（GUI 工具 rqt 依赖）、python3-nose 失败（Python 3.12+ 废弃），均不影响核心功能。

### 编译源码

**编译策略：** RMW 使用 Cyclone DDS（不编译 Connext 等商业中间件），只构建到 demo_nodes 的最小依赖链（Fast DDS 库仍会作为依赖自动编译）：

```bash
cd /root/ros2_humble
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp

# 实测建议：3.9 GB 内存无 swap，限并行度防止编译高峰设备卡死（见编译问题 2）
colcon build --symlink-install \
  --packages-up-to demo_nodes_cpp demo_nodes_py \
  --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF \
  --parallel-workers 1 \
  --packages-skip \
  rmw_connextdds rmw_connextdds_common rmw_connextddsmicro rti_connext_dds_cmake_module \
  rviz_assimp_vendor tinyxml_vendor libcurl_vendor zstd_vendor sqlite3_vendor \
  yaml_cpp_vendor shared_queues_vendor

```

实测编译约 130 个包。编译完成后追加构建 `ros2cli` 命令行工具（含其依赖包，见编译问题 4）：

```bash
source /root/ros2_humble/install/setup.bash
colcon build --packages-select geometry_msgs std_srvs rosidl_runtime_py \
  ros2cli ros2node ros2topic ros2msg ros2service ros2action ros2param ros2pkg ros2run \
  --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF

```

### 编译问题与解决方法（实测）

**问题 1：colcon 命令不存在（command not found）**

Debian 的 `python3-colcon-core` 仅提供库无 CLI 入口，需额外安装 `colcon` 包：

```bash
apt-get install -y colcon

```

**问题 2：编译高峰期设备卡死/自动重启**

编译 demo_nodes 链时设备多次卡死（无 OOM 记录、温度 56–59°C 正常），疑似高负载引发。缓解：限核 + 降优先级 + 串行编译：

```bash
taskset -c 0-3 nice -n 10 colcon build --symlink-install \
  --packages-up-to demo_nodes_cpp demo_nodes_py \
  --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF \
  --parallel-workers 1 \
  --packages-skip \
  rmw_connextdds rmw_connextdds_common rmw_connextddsmicro rti_connext_dds_cmake_module \
  rviz_assimp_vendor tinyxml_vendor libcurl_vendor zstd_vendor sqlite3_vendor \
  yaml_cpp_vendor shared_queues_vendor

```

编译中断后 `colcon build` 支持增量续编：保留 build/ 与 install/ 目录直接重跑命令即可，已完成的包会跳过。

**问题 3：rclpy 报 file too short（.so 为 0 字节）**

设备重启中断编译导致 `_rclpy_pybind11.cpython-313-aarch64-linux-gnu.so` 写入不完整（0 字节）。删除 build/rclpy 与 install/rclpy 后重新编译：

```bash
rm -rf build/rclpy install/rclpy
colcon build --packages-select rclpy \
  --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF

```

**问题 4：ros2 缺 ros2run / ros2topic 依赖包**

`ros2 run` 需要 ros2run（依赖 ros2pkg）；ros2topic/ros2service 还依赖 geometry_msgs、std_srvs、rosidl_runtime_py（不在 demo_nodes 依赖链中）。按上面「编译源码」一节补充构建即可。

## 环境变量设置

编译完成后，将 ROS 2 环境写入 `~/.bashrc` 实现自动加载：

```bash
echo 'source /root/ros2_humble/install/setup.bash' >> ~/.bashrc
echo 'export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp' >> ~/.bashrc
source ~/.bashrc

```

## 使用测试

打开一个终端，运行 C++ talker：

```bash
ros2 run demo_nodes_cpp talker

```

打开另一个终端，运行 Python listener：

```bash
ros2 run demo_nodes_py listener

```

### 验证

实测输出：

```
[INFO] [talker]: Publishing: 'Hello World: 1'
[INFO] [listener]: I heard: [Hello World: 15]

```

也可用 ros2 命令行验证话题：

```bash
ros2 topic list          # 应显示 /chatter /parameter_events /rosout
ros2 topic info /chatter # Type: std_msgs/msg/String, Publisher count: 1
ros2 node list           # 应显示 /listener /talker

```

C++ 与 Python API 互通正常，ROS 2 Humble 环境可用于后续应用开发。

## 常见问题

### ros2 命令只显示部分子命令（缺 run/topic 等）

实测现象：只执行 `colcon build --packages-up-to demo_nodes_cpp demo_nodes_py` 后，`ros2 run` 报 `invalid choice: 'run'`，因 demo_nodes 依赖链不含 ros2cli 扩展包。需补充构建（见编译源码一节）：

```bash
colcon build --packages-select geometry_msgs std_srvs rosidl_runtime_py \
  ros2cli ros2node ros2topic ros2msg ros2service ros2action ros2param ros2pkg ros2run \
  --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF

```

### rclpy 报 file too short（.so 为 0 字节）

设备重启中断编译导致 `_rclpy_pybind11.cpython-313-aarch64-linux-gnu.so` 写入不完整，`ros2 --help` 直接 ImportError。删除 build/rclpy 与 install/rclpy 后重编（见编译问题 3）。

### pip3 install 报 externally-managed-environment（PEP 668）

Debian 13 默认禁止 pip 写入系统 Python 环境。实测 `lark`、`netifaces` 已随系统预装，无需安装；确需安装时加参数：

```bash
pip3 install --break-system-packages lark netifaces

```

### 后台编译进程随 adb shell 退出被终止

实测 `nohup ... &` 方式启动编译进程，adb 会话结束后进程被 SIGHUP 杀掉，日志未生成。改用 `setsid` 或 systemd service 托管：

```bash
# systemd 方式
cat > /etc/systemd/system/ros2-build.service << 'EOF'
[Unit]
Description=ROS2 build
[Service]
Type=simple
ExecStart=/bin/bash /root/ros2_humble/build.sh
WorkingDirectory=/root/ros2_humble
StandardOutput=append:/root/ros2_humble/build.log
StandardError=append:/root/ros2_humble/build.log
[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload && systemctl start ros2-build.service

```

### 系统无法启用 swap（Function not implemented）

内核未启用 CONFIG_SWAP 与 zram，`swapon /swapfile` 报 `Function not implemented`。3.9 GB 内存无 swap，编译必须限制并行度（见编译问题 2），不可依赖 swap 缓解。